fix(dflash-speculator): guard capture() log on needs_capture() (#53031) - #53096

Bugfix

Fixes #53031 — DFlashSpeculator.capture() logged "Capturing model for ... speculator" unconditionally, even when init_cudagraph_manager resolved to CUDAGraphMode.NONE and the capture loop did nothing.

That line is the only externally visible signal for whether the drafter is captured, so an unconditional log made the drafter-capture state unobservable from outside the process.

Reproducer

Run any DFlash setup where draft attention does not support full cudagraphs (e.g. uniform batch < AttentionCGSupport.UNIFORM_BATCH, or runner decode mode not FULL). Inspect the worker log: the "Capturing model ..." line prints once per worker even though the discoverer returned early on if not (self.cudagraph_mode and capture_sizes) and _capture_descs stayed empty.

Fix

Mirror the model runner's existing guard pattern at vllm/v1/worker/gpu/model_runner.py:

def capture(self) -> None:
+    assert self.query_cudagraph_manager is not None
+    if not self.query_cudagraph_manager.needs_capture():
+        return
     logger.info("Capturing model for %s speculator...", self._speculator_name)
     ...

needs_capture() already exists on the manager (returns len(self._capture_descs) > 0). The early-return matches the model runner pattern exactly, so the only operator-visible difference is that the log line becomes an accurate proxy for "something was actually captured".

The reporter proposed this exact diff in the bug report — submitting it as a PR with a regression test so future changes can't quietly regress.

Files

Diff: +87 / -1, 2 files.

Risk

Behavioural change is limited to the log surface. The assert was already correct (asserts a stronger precondition than the existing code used); the early-return was the gap. No data-flow or API changes. The full capture path is unchanged when there is something to capture.

Local verification

• pytest tests/v1/spec_decode/test_dflash_speculator_capture.py -v — 2 tests pass.
• Test follows the existing SimpleNamespace + unittest.mock.MagicMock pattern from tests/v1/spec_decode/test_dflash_prepare_inputs.py so it stays hermetic. CPU-only because DFlashSpeculator.__init__ requires a real VllmConfig; the capture() method itself only reads attributes, so the mock-based harness is clean.

Notes for maintainers

• Marked fix(...) rather than feat(...) because it changes an observable log rather than adds new functionality.
• The needs_capture() API predates this PR and is already imported by the model runner, so no new cross-file surface area is introduced.
• Followed the same review momentum: the reporter's quoted diff maps 1:1 to the source change; the test file is the only addition.